클로드 코드 완벽 가이드 — 18장 기능 작업하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

18장에서 다루는 내용

• MVP 기능 정의하기 — 최소한의 핵심 기능을 정하고 단계별 실행 계획 세우기
• MVP 기능 구현하기 — 플래닝 모드와 Phase별 점진적 구현
• 멀티에이전트 작업 준비하기 — 여러 터미널에서 동시에 작업하는 전략
• 필수 커스텀 커맨드 생성하기 — feature-breakdown, create-issue, resolve-issue 커맨드
• 워크트리 매크로 제작하기 — 깃 워크트리로 병렬 개발 환경 구축
• 상세페이지 작업하며 동시에 플래닝하기 — 이슈 기반 워크트리 작업 + PR 머지 워크플로우
• 여러 작업 동시에 실행하기 — 독립적인 이슈를 병렬로 처리하는 멀티에이전트 코딩

전체 흐름도

[MVP 기능 정의]          [MVP 기능 구현]           [멀티에이전트 작업]
    |                        |                        |
    v                        v                        v
+------------------+   +--------------------+   +------------------------+
| 개선점 목록 작성   |   | Shift+Tab 플래닝    |   | 워크트리 매크로 제작     |
| = 핵심 가치 기능   |   | SPEC.md 작성        |   | = create-worktree.sh   |
|                  |   |                    |   |                        |
| 클로드 코드에      |   | Phase별 실행         |   | 커스텀 커맨드 3종        |
| 계획 요청         |   | * Phase 1: 구조정리  |   | * feature-breakdown    |
|                  |   | * Phase 2: 평점개선  |   | * create-issue         |
| SPEC.md에 저장    |   | * Phase 3~6: ...    |   | * resolve-issue        |
+------------------+   +--------------------+   +------------------------+
        |                        |                        |
        v                        v                        v
+------------------------------------------------------------------+
| 상세페이지 작업 + 동시 플래닝                                      |
| 이슈 생성 -> 워크트리 생성 -> 구현 -> 커밋 -> PR -> 머지 -> pull    |
| 터미널 1: issue-2 (좋아요 버튼) | 터미널 2: issue-3 (필터 Select)  |
+------------------------------------------------------------------+

핵심 키워드

18-1 MVP 기능 정의하기

한 줄 요약

MVP는 "이 기능 없이 서비스가 성립할 수 있을까?"를 기준으로 최소한의 핵심 기능만 골라서 먼저 구현하고 배포하는 전략이다.

쉬운 설명 (비유)

MVP = 식당 오픈 비유

❌ 나쁜 접근: 100가지 메뉴를 한꺼번에 준비
  -> 시간/비용 폭발, 손님이 뭘 좋아하는지도 모름

✅ 좋은 접근: 대표 메뉴 3가지만 먼저 오픈
  -> 빠르게 손님 반응 확인 -> 인기 메뉴 확장
  -> 이게 바로 MVP!

MVP 기능 정의 절차

Step 1: 개선점 목록 작성
  현재 사이트에서 개선해야 할 점을 구체적으로 나열
  예) - 불필요한 페이지 삭제
      - 별점 -> 좋아요/싫어요 시스템으로 변경
      - 필터 재설계 (예산, 지역, 환경, 계절)
      - 카드 구조 변경 (Key-Value 표시)

Step 2: 클로드 코드에게 계획 요청
  새로운 대화창에서 개선점을 전달하고
  Phase별 실행 계획 수립을 요청

Step 3: 계획 검토 및 SPEC.md 저장
  생성된 계획을 Markdown 파일로 저장
  Bullet Point와 Phase를 체크박스로 표시

실무 예제 — K-NOMAD HUB 개선점 목록

❌ 삭제할 것:
  - 홈페이지/인증 외 불필요 페이지 전부 삭제
  - 별점 평점 삭제
  - 프로필 관련 버튼 제외한 내비게이션 버튼 삭제
  - '자세히 보기' 버튼 삭제

✅ 추가/변경할 것:
  - [좋아요] [싫어요] 버튼 구현
  - 필터: 예산(100만원/100~200/200만원), 지역(수도권/경상도/...),
          환경(자연친화/도심선호/...), 최고 계절(봄/여름/가을/겨울)
  - 카드에 필터 정보를 Key-Value로 표시
  - 가짜 데이터 수정 (도시별 필터 요소 추가)
  - 'TOP 추천 도시' -> '도시 리스트'로 변경

Phase별 계획 예시

Phase 1: 코어 구조 정리 및 내비게이션 단순화
  - /cities, /compare, /community, /guides 페이지 삭제
  - Header.tsx 내비게이션 정리
  - 사용하지 않는 컴포넌트/파일 정리

Phase 2: 평점 시스템 개선 (별점 -> 좋아요/싫어요)
  - CityCard 컴포넌트 수정
  - 상태 관리 로직 구현
  - 관련 컴포넌트 업데이트

Phase 3~6: 필터, 카드 구조, 데이터, 제목 변경 등

핵심 체크포인트

• MVP의 기준 = "이 기능 없이 서비스가 성립할 수 있을까?"
• 욕심을 줄이고 본질에 집중하는 게 MVP의 핵심
• 큰 작업을 Phase별로 나누면 각 단계가 독립적으로 실행 가능
• SPEC.md에 계획을 저장하면 장기간 기억하고 체계적으로 관리 가능

18-2 MVP 기능 구현하기

한 줄 요약

플래닝 모드(Shift+Tab 두 번)로 Phase별 상세 계획을 세운 뒤, 클로드 코드의 Todo 리스트를 활용해 하나씩 체계적으로 구현한다.

쉬운 설명 (비유)

플래닝 모드 = 건축 설계도

❌ 설계도 없이 바로 건축 시작
  -> 기둥 위치 엉뚱, 배관 충돌, 전체 재시공

✅ 설계도를 먼저 완성하고 공사 시작
  -> 1층 완성 -> 검수 -> 2층 시작 -> 검수 -> 완성
  -> Phase별 구현이 바로 이 방식!

플래닝 모드 활용법

Step 1: Shift+Tab 두 번 -> 플래닝 모드 진입
  "@SPEC.md 파일의 Phase 1을 어떻게 구현할지
   계획해라. 작업 끝나면 lint와 typecheck를 실행해서
   문제 해결해라."

Step 2: 클로드 코드가 상세 실행 계획(Execution Plan) 생성
  - Tasks to Complete 목록
  - Verification Steps
  - Expected Outcome

Step 3: 계획 확인 후 실행
  Todo 리스트가 자동 생성되어 하나씩 체크하며 진행

실무 예제 — Phase 1 실행 결과

Phase 1 Implementation Plan: Core Structure Cleanup

Tasks to Complete:
1. Delete Page Directories
   - /src/app/cities/ 삭제
   - /src/app/compare/ 삭제
   - /src/app/community/ 삭제
   - /src/app/guides/ 삭제

2. Update Header Navigation
   - 삭제된 페이지의 메뉴 항목 제거
   - 인증 관련 요소만 유지

3. Clean Up Components
   - 사용하지 않는 컴포넌트 제거
   - 깨진 링크 수정

4. Verification Steps
   - 홈페이지(/) 정상 로드 확인 (HTTP 200)
   - 로그인/회원가입 페이지 정상 작동 확인
   - 삭제된 페이지 404 반환 확인

모델 선택 팁

작업 난이도에 따른 모델 선택:

난이도 낮은 작업 (Phase 1처럼 단순 삭제/정리):
  -> Sonnet 모델 사용 -> 빠르고 저렴

난이도 높은 작업 (복잡한 로직 구현):
  -> Opus 모델 사용 -> 정확하고 깊은 추론

핵심: Sonnet도 다룰 수 있는 수준이면
      Opus에게 맡기지 않고 Sonnet에게 맡기면
      엄청난 시간 절약 가능!

CLAUDE.md 활용 팁

프롬프트 마지막에 추가하면 좋은 규칙들:

"각 단계별 구현이 끝날 때마다
 lint와 typecheck를 실행해서
 프로젝트에 문제가 없는지 확인하고
 문제가 있다면 해결해줘.
 끝난 작업은 확인할 수 있도록
 Checkbox에 체크해줘."

-> 이런 내용을 CLAUDE.md에 명시해두면
   매번 프롬프트에 반복할 필요 없음!

핵심 체크포인트

• Shift+Tab 두 번 = 플래닝 모드 진입
• 너무 세세한 플래닝은 오히려 역효과 (단계 간 문맥 단절)
• 작업 시작 전 에이전트 상황을 전반적으로 파악시키는 게 좋음
• lint + typecheck 자동 실행을 습관화
• 에러 발생 시 에러 로그를 복사해서 클로드 코드에 붙여넣기

18-3 멀티에이전트 작업 준비하기

한 줄 요약

서비스의 중심이 잡히면 여러 터미널에서 클로드 코드를 동시에 실행하여 기능 작업, 데이터베이스 작업, 버그 수정 등을 병렬로 처리하는 멀티에이전트 전략을 활용한다.

쉬운 설명 (비유)

멀티에이전트 = 음식점 주방

1인 셰프: 재료 손질 -> 조리 -> 플레이팅 (순차 처리)
  -> 하나씩 하면 느림

멀티 셰프: 셰프A가 재료 손질하는 동안
           셰프B가 소스 준비, 셰프C가 디저트 제작
  -> 독립적인 작업을 동시에! = 멀티에이전트

⚠️ 주의: 검수가 몰리면 대충 검수하게 됨
   -> 바이브 코딩할 때 매우 경계해야 할 상황!

우리의 역할 = 플래닝

에이전트 = 직접 코딩하는 주니어 개발자
우리     = 숲을 바라보는 시니어 개발자 / 프로덕트 오너

핵심 원칙:
1. 계획을 충분히 작고, 상세하고, 세밀하게 세우기
2. 클로드 코드가 코드를 작성하는 동안 다음 작업 플래닝
3. 검수 업무가 몰릴 때 대충 넘기지 않기
4. 초반에는 의도를 넘어서는 과한 설계 경계
5. 명확히 의도한 기능만 개발되었는지 확인

핵심 체크포인트

• 병목이 되는 작업(초기 기능, DB, 크리티컬 버그)은 두 개 이상의 터미널 동시 활용
• 클로드 코드가 코드 작성하는 시간에 플래닝을 동시 진행
• 검수 업무가 몰려도 본능적으로 대충하지 않도록 경계
• 프로젝트가 커질수록 환각이 심해지므로 결과 검증 필수

18-4 필수 커스텀 커맨드 생성하기

한 줄 요약

반복적으로 사용하는 프롬프트를 .claude/commands/ 폴더에 커스텀 커맨드로 저장하면, 프로젝트가 진행될수록 클로드 코드가 더욱 최적화된다.

쉬운 설명 (비유)

커스텀 커맨드 = 자주 쓰는 문자 템플릿

❌ 매번 처음부터 긴 프롬프트 작성
  -> 시간 낭비, 매번 다른 결과

✅ 검증된 프롬프트를 템플릿으로 저장
  -> /feature-breakdown 도시 상세페이지
  -> /create-issue 지금까지 세운 계획을 깃허브 이슈로
  -> /resolve-issue 1
  -> 항상 일관된 고품질 결과!

커스텀 커맨드 (1) feature-breakdown

파일 위치: .claude/commands/feature-breakdown.md

기능: 구현하고 싶은 기능을 입력하면
      체계적으로 작은 작업 단위로 분해된 실행 계획 제공

구조:
  1. 기능 분석 — 핵심 목표, 범위 정의, 사용 케이스
  2. 아키텍처 분해 — 프런트엔드/백엔드/외부 연동
  3. 작업 분해 — [우선순위] 작업명, 설명, 예상 시간, 의존성, 완료 조건, 파일/경로
  4. 의존성 관계 — 병렬 처리 가능 / 순차 처리 필요 / 블로커
  5. 검증 계획 — 단위/통합/사용성 테스트
  6. 진행 추적 — 마일스톤, 리스크 요소, 롤백 계획
  7. 배포 전략 — 스테이징 검증, 점진적 배포, 모니터링

사용 예:
  /feature-breakdown 도시 상세페이지를 만들고 싶어

커스텀 커맨드 (2) create-issue

파일 위치: .claude/commands/create-issue.md

기능: $ARGUMENT로 입력한 내용을 깃허브 이슈로 생성

작업 지침:
  1. 요청 분석 — 작업 유형과 우선순위 결정
  2. 프로젝트 라벨링 시스템 적용 (CLAUDE.md 참조)
     - 작업 유형: feature, refactor, ui/ux, cleanup, enhancement
     - 우선순위: high-priority, medium-priority, low-priority
     - 상태: idea (새로운 제안)
  3. 이슈 생성 내용 — 명확한 제목, 상세 설명, 라벨, 완료 조건
  4. 마크다운 형식으로 전문적으로 작성
  5. gh issue create 명령어로 저장소에 이슈 생성

사용 예:
  /create-issue 지금까지 세운 계획을 깃허브 이슈로 생성해줘

커스텀 커맨드 (3) resolve-issue

파일 위치: .claude/commands/resolve-issue.md

기능: 깃허브 이슈 번호를 입력받아 분석하고
      상세한 구현 계획을 수립한 뒤 사용자 검토 후 진행

절차:
  1. 이슈 정보 가져오기 — gh issue view {issue-number}
  2. 이슈 분석 — 요구사항 파악, 관련 파일/컴포넌트, 기술적 고려사항
  3. 구현 계획 수립 — 작업 분해, 예상 시간, 파일 변경, 테스트 계획
  4. 사용자 검토 요청 — 계획 적절성, 누락 점검, 우선순위 조정

핵심: 계획을 TodoWrite 도구로 구조화하고,
      사용자 승인을 받은 후에만 구현을 진행

사용 예:
  /resolve-issue 1

실무 예제 — feature-breakdown 실행 결과

/feature-breakdown 도시 카드를 눌렀을 때 이동할 상세페이지를 제작하고 싶어

결과:
  1. 기능 분석
     - 핵심 목표: 도시 카드 클릭 -> 상세 페이지로 이동
  2. 아키텍처 분해
     - 프런트엔드: /cities/[id]/page.tsx (동적 라우트)
     - 백엔드: cities.json 데이터 활용
  3. 작업 분해
     [HIGH] 동적 라우팅 페이지 생성 (2시간)
     [HIGH] 도시 카드 내비게이션 추가 (1시간)
     ...
  4. 의존성 관계
     순차: 동적 라우트 -> 데이터 로딩 -> CityCard 링크
     병렬: 이미지 갤러리 <-> 점수 시각화
     블로커: 동적 라우트가 다른 모든 작업의 전제 조건

핵심 체크포인트

• 커스텀 커맨드는 .claude/commands/ 폴더에 Markdown 파일로 저장
• $ARGUMENT 변수로 사용자 입력을 동적으로 받음
• 결과가 마음에 안 들면 커맨드 파일 자체를 수정 (출력을 직접 수정하지 않음)
• 프로젝트가 진행될수록 커스텀 커맨드가 누적되어 효율이 기하급수적으로 향상

18-5 워크트리 매크로 제작하기

한 줄 요약

Git 워크트리를 생성하고 이동한 뒤 클로드 코드를 실행하는 셸 스크립트를 만들면, 이슈별로 독립된 브랜치에서 병렬 작업을 간편하게 시작할 수 있다.

쉬운 설명 (비유)

워크트리 = 작업실 여러 개

❌ 작업실 1개: 그림 그리다가 목공하려면
   그림 도구 치우고 목공 도구 꺼내야 함
   -> 브랜치 전환할 때마다 컨텍스트 스위칭 비용

✅ 작업실 여러 개: 작업실A는 그림, 작업실B는 목공
   각 작업실에서 독립적으로 동시 작업 가능
   -> 워크트리별로 다른 브랜치를 동시 체크아웃!

create-worktree.sh 스크립트

#!/bin/bash
# 워크트리 이름을 인수로 받아 생성하고 이동

if [ $# -eq 0 ]; then
    echo "Error: 워크트리 이름을 입력해주세요!"
    return 1
fi

ARGUMENT=$1
WORKTREE_PATH="../worktree/$ARGUMENT"

if git worktree add "$WORKTREE_PATH"; then
    echo "워크트리 생성 성공: $WORKTREE_PATH"
    cd "$WORKTREE_PATH" || return 1
    echo "디렉터리 변경 완료 $(pwd)"
    claude    # 워크트리에서 클로드 코드 실행
else
    echo "워크트리 생성에 실패했습니다."
    return 1
fi

실행 방법

주의: 반드시 . (dot)이나 source를 붙여서 실행!

✅ 올바른 실행:
  . ./create-worktree frontend
  . ./create-worktree issue-82

❌ 잘못된 실행:
  ./create-worktree frontend
  -> 스크립트 내부의 cd가 서브셸에서만 적용
  -> 현재 셸의 디렉터리는 안 바뀜!

이유: . 또는 source를 붙이면 스크립트가
      현재 셸에서 직접 실행되므로
      cd로 바꾼 작업 디렉터리가 그대로 유지됨

워크트리 사용 시 주의사항

워크트리는 브랜치를 생성하는 개념이므로:

1. 커밋 필수: 워크트리를 생성하기 전에
   현재 작업 내용을 반드시 커밋해야 함
   (커밋하지 않은 코드는 워크트리에 복사 안 됨)

2. 이슈 번호 활용: 워크트리 이름에 이슈 번호 사용
   . ./create-worktree issue-1
   -> 작업 이름이 겹치지 않고 추적 가능

핵심 체크포인트

• 워크트리 = 하나의 저장소에서 여러 브랜치를 동시에 체크아웃하는 디렉터리
• . ./create-worktree 형태로 실행해야 현재 셸에 cd가 반영됨
• 워크트리 생성 전 반드시 기존 작업 커밋 필수
• 이슈 번호를 워크트리 이름으로 사용하면 작업 추적에 편리

18-6 상세페이지 작업하며 동시에 플래닝하기

한 줄 요약

이슈를 생성하고, 이슈 번호로 워크트리를 만들어 독립 브랜치에서 작업한 뒤, 풀 리퀘스트로 검수 후 머지하는 전체 워크플로우를 실습한다.

쉬운 설명 (비유)

이슈 기반 워크플로우 = 택배 배송 시스템

1. 주문 접수 (이슈 생성)
   /feature-breakdown 도시 상세페이지
   /create-issue 지금까지 구현한 계획을...

2. 포장 라인 배정 (워크트리 생성)
   . ./create-worktree issue-1

3. 포장 작업 (구현)
   /resolve-issue 1 -> 계획 확인 -> "구현을 시작해줘"

4. 품질 검수 (PR 생성)
   "현재까지 작업을 기반으로 Pull Request를 만들어줘"

5. 출고 (머지)
   깃허브에서 PR 확인 -> Merge pull request

6. 재고 동기화 (pull)
   git pull origin main

전체 워크플로우

[이슈 분해]                     [워크트리 작업]
/feature-breakdown              . ./create-worktree issue-1
    |                               |
    v                               v
[이슈 생성]                     [구현 실행]
/create-issue                   /resolve-issue 1
    |                               |
    v                               v
[깃허브 이슈 확인]              [커밋]
깃허브에서 #1 확인               "현재까지 작업 내용을 커밋해줘"
                                    |
                                    v
                                [PR 생성]
                                "Pull Request를 만들어줘"
                                    |
                                    v
                                [머지]
                                깃허브에서 Merge pull request
                                    |
                                    v
                                [메인에서 pull]
                                git pull origin main

실무 예제 — 도시 상세페이지 구현 결과

PR: 기능: 포괄적인 도시 상세 페이지 및 향상된 UI 컴포넌트 구현 #3

변경 사항:
  - 동적 라우팅 포함한 도시 상세 페이지 시스템 구현
  - 브레드크럼 내비게이션과 주요 지표가 있는 CityHero 컴포넌트 추가
  - 8개 점수 카테고리에 대한 시각적 진행률 표시 SityStats 컴포넌트 생성
  - 상세한 도시 정보 섹션이 있는 CityDetail 컴포넌트 구축
  - 통계 시각화를 위한 재사용 가능 Progress UI 컴포넌트 추가
  - 향상된 스타일링과 내비게이션 링크로 CityCard 컴포넌트 개선

변경 파일 (8 files, 421 insertions, 3 deletions):
  - src/app/cities/[id]/page.tsx (신규)
  - src/components/cities/CityDetail.tsx (신규)
  - src/components/cities/CityHero.tsx (신규)
  - src/components/cities/CityStats.tsx (신규)
  - src/components/ui/progress.tsx (신규)
  - src/components/cities/CityCard.tsx (수정)

핵심 체크포인트

• 상세페이지를 구현하는 동안 다른 이슈를 동시에 플래닝 가능
• /resolve-issue는 계획만 먼저 세우고 사용자 검토 후 구현 시작
• 모든 작업물은 직접 로컬에서 머지하지 않고 PR을 통해 검수 후 머지
• 워크트리 폴더(../worktree/issue-1)에서 서버를 실행해 결과 확인

18-7 여러 작업 동시에 실행하기

한 줄 요약

독립적인 이슈 두 개를 각각 별도의 터미널과 워크트리에서 동시에 작업하면, 머지 컨플릭트 없이 병렬로 기능을 구현할 수 있다.

쉬운 설명 (비유)

동시 작업 = 두 명의 인테리어 전문가

독립적인 작업이라면 동시에 가능:
  인테리어A: 거실 커튼 교체 (터미널 1 / issue-2)
  인테리어B: 주방 싱크대 교체 (터미널 2 / issue-3)
  -> 서로 다른 공간이라 충돌 없음!

주의: 같은 파일을 수정하면 충돌 발생:
  두 사람이 동시에 같은 벽에 페인트칠
  -> 머지 컨플릭트!

병렬 작업 실행 절차

사전 준비: 독립적인 이슈 두 개를 미리 생성
  - issue-2: [좋아요] 버튼 레이아웃 변경
  - issue-3: 필터 Select 최대 너비 변경

[터미널 1]
  . ./create-worktree issue-2
  /resolve-issue 2

[터미널 2]
  . ./create-worktree issue-3
  /resolve-issue 3

-> 두 작업이 동시에 진행!
-> 완료 후 각각 서버 실행해서 검수
-> 각각 PR 생성 후 깃허브에서 머지

핵심 체크포인트

• 독립적인 작업(서로 다른 파일 수정)이면 동시 작업 시 머지 컨플릭트 가능성 낮음
• 각 터미널마다 별도 워크트리 + 별도 브랜치에서 작업
• 작업 완료 후 서버 실행은 해당 워크트리 폴더에서 실행
• 작업 완료 순서: 구현 -> 검수 -> 커밋 -> PR 생성 -> 깃허브 머지

연습문제 풀이

Q1: MVP 기능 정의 시 가장 중요한 기준은 무엇인가?

A: "이 기능 없이 이 서비스가 성립할 수 있을까?"를 기준으로 판단한다. 핵심 가치를 전달할 수 있는 최소한의 기능만 골라야 하며, 욕심을 줄이고 본질에 집중하는 것이 MVP의 핵심이다.

Q2: 플래닝 모드에 진입하는 단축키와, 너무 세세한 플래닝이 위험한 이유는?

A: Shift+Tab을 두 번 눌러 플래닝 모드에 진입한다. 너무 세세하게 단계별 플래닝을 하면, 몇 단계가 실행된 후의 문맥과 이어지지 않아 문맥 단절이 발생할 수 있다. 작업을 실행할 때 현재 에이전트의 상황을 전반적으로 파악하도록 하는 것이 좋다.

Q3: 커스텀 커맨드의 $ARGUMENT 변수는 어떤 역할을 하는가?

A: $ARGUMENT는 커스텀 커맨드 실행 시 사용자가 입력하는 값을 받는 자리표시자이다. 예를 들어 /feature-breakdown 도시 상세페이지에서 "도시 상세페이지"가 $ARGUMENT에 대입된다. 이를 통해 하나의 커맨드 템플릿으로 다양한 입력에 대해 일관된 형식의 결과를 생성할 수 있다.

Q4: 워크트리 생성 스크립트를 . ./create-worktree로 실행해야 하는 이유는?

A: . 또는 source를 붙이지 않고 ./create-worktree로 실행하면, 스크립트가 서브셸에서 실행되어 cd로 변경한 디렉터리가 현재 셸에 적용되지 않는다. . 을 붙이면 현재 셸에서 직접 실행되므로 워크트리 디렉터리로의 이동이 그대로 유지된다.

부록 A: 용어 사전

부록 B: 핵심 비교표

부록 C: 추천 참고 자료 & 링크